<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>ESP8266 ILI9341 display support code with printf sources, wire-frame viewer and custom fonts: font_to_svg</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">ESP8266 ILI9341 display support code with printf sources, wire-frame viewer and custom fonts
   &#160;<span id="projectnumber">1.0</span>
   </div>
   <div id="projectbrief">ESP8266ILI9341DisplayProject</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">font_to_svg </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This code will convert a single character in a TrueType(R) font file into an SVG 'path' shape.</p>
<h3>basic usage:</h3>
<p>Let's say you have a TrueType font file, such as the popular FreeSans.ttf. Let's pull out the path information for the letter "B" and transform it into SVG. A simple C++ program code like the following can do that. </p><pre class="fragment">#include &lt;font_to_svg.hpp&gt;
int main()
{
    font_to_svg::glyph g( "FreeSans.ttf", 66 );
    std::cout &lt;&lt; g.outline();
}
</pre><p>Compile and run, and the program will generate an SVG path out of the TrueType information for the character of Unicode U+0066 (the Latin letter B), something like this: </p><pre class="fragment">&lt;svg&gt;
&lt;path d='M 591,-180 Q 591,-150 580,-121 Q 569,-92 543,-63 ... Z /&gt;
&lt;/svg&gt;
</pre><p>'M' is 'move to', and 'Q' is for Bezier curves. Open the resulting .svg file in a web browser and you get something like this:</p>
<div class="image">
<img src="screenshot.png"  alt="Rendering of font glyph" title="The Letter B"/>
</div>
<p>Another example: Floral Heart, Unicode 0x2766:</p>
<div class="image">
<img src="screenshot2.png"  alt="Rendering of font glyph" title="Floral Heart"/>
</div>
<h3>Current Status</h3>
<p>This project has some bugs but will handle 'standard' fonts reasonably well.</p>
<p>Currently this project consists of a C++ language header that can used in conjuction with the Freetype library to create a basic conversion program that will extract a single character from a .ttf file and create a matching .svg file.</p>
<p>The program is stable for basic use. It can output plain glyph shapes or it can also output 'debugging' information like the node points &amp; lines. There are some bugs with bounding boxes and other 'typographic box' issues like Bearing. Also calculation of the SVG "g" tag has some issues with transforms/footers.</p>
<p>The code does not currently support OpenType or it's features, such as ligatures. It does not support creating an "SVG Font". It only does very basic conversion of Truetype glyphs to SVG path shapes. It might not be useful for web fonts or other usages.</p>
<h3>More example programs</h3>
<p>There are several example programs included. They use the cmake build system ( <a href="http://www.cmake.org">http://www.cmake.org</a> ). For example: </p><pre class="fragment"> cmake .
 make
 ./example1 `locate tahoma.ttf` 66 &gt; out.svg 
 firefox out.svg
</pre><p>Example 1 and Example 2 just do basic output of a single character into a .svg path. The first argument is a truetype font filename, and the second argument is a Unicode codepoint number. For example: </p><pre class="fragment">./example2 ./FreeSerif.ttf 66 &gt; example2.svg 
</pre><p>In the line above, 66 = unicode/ascii for the letter 'B'. You can use hexadecimal numbers as well. For example, the Cherokee Letter O has hexadecimal Unicode point 0x13A3: </p><pre class="fragment">./example1 ./FreeSerif.ttf 0x13A3 &gt; example2.cho.svg
</pre><p>To view the resulting svg file, it is easiest to use a browswer like Firefox. Go to 'file/open' and point it to your output file. Or type something like '<a href="file:///tmp/x.svg'">file:///tmp/x.svg'</a> into your address bar. You can also get the Firefox addon that can auto-reload files when they change on disk.</p>
<p>Another option is to use svg view/edit programs like Inkscape.</p>
<p>Example 3 was created by github user Ebraminio to generate multiple .svg files from a single GPL font of ancient Persian letters ( Xerxes.ttf, available by a web search )</p>
<h3>Detail on using in your own project</h3>
<p>As noted, font_to_svg is a 'header library' so you dont need to compile any libraries just include the header and use it. You will still need to link to Freetype however, using your build system.</p>
<p>Freetype's website is here: <a href="http://www.freetype.org/">http://www.freetype.org/</a></p>
<p>font_to_svg uses freetype to deal with vaguaries and variations of Truetype file formats. font_to_svg does not use any of Freetype's bitmap font-rendering code. font_to_svg is a pure "outline curve" renderer to be used for vector/curve based output.</p>
<p>Font_to_svg comes with a very permissive BSD style copyright license described in the LICENSE file in this distribution. Acknowledgment in the product documentation would be appreciated but is not required.</p>
<p>To understand the usage, look at the files named 'example*.cpp' that come with the source code. You can output the bare svg path data, or a bunch of debugging information.</p>
<p>Don't forget that some fonts have restrictive copyright licenses that forbid this type of conversion. You can use fonts from <a href="http://openfontlibrary.org">http://openfontlibrary.org</a> If you want to be safe from accusations of copyright violation.</p>
<h3>Finding cool Unicode points</h3>
<p><a href="http://www.fileformat.info/info/unicode/block/index.htm">http://www.fileformat.info/info/unicode/block/index.htm</a></p>
<h3>How does Truetype actually work then? How does this program work?</h3>
<p>Truetype fonts consist of a group of characters layed out in a file. The truetype file format is very complicated, with various issues related to character sets, glyph indexes, duplicated positions, etc etc etc. font_to_svg uses the Freetype library to make it easy to deal with those problems and to load the file into memory.</p>
<p>Each character in the Truetype file has a sequence of 'contours', which are basically a sequence of curves and lines that form a single shape. Some contours count as the 'body' of the letter, while others are the 'holes' of a letter. The letter 'B' for example has a single contour for the 'outside' shape, and two 'hole' contours for the two inside shapes.</p>
<p>Truetype marks these contours in a special way - by the 'clockwise' ness of the order in which it lists the points that make up a contour. The contours that have their points in 'clockwise' order are considered 'solid' The contours that have their points listed in 'counter clockwise' (also called 'anti-clockwise') order are considered 'holes'. For example, imagine the letter 'o'. The points making up the 'outside' contour are listed in clockwise order, while the points making up the 'inside' contour are listed in counter-clockwise order.</p>
<p>But what type of points make up a contour? They are simple 2-dimensional Cartesian points with integer coordinates. The points for a contour are listed in order in the Truetype file. The curves and lines of a contour are drawn between the points using the rules of Bezier Curves. This means there are actually two different types of points - 'on the curve' points and 'off the curve' points. The 'on the curve' points actually have lines or curves coming out of them and/or touching them. 'Off the curve' curves represent the 'control' points between the 'on the curve' points.</p>
<p>Now, Truetype doesn't just use any old Bezier curve. It uses a type of Bezier called 'Quadratic', which consists of two endpoints 'on the curve' and one 'control point'. If you check the Wikipedia article for Bezier Curve, <a href="http://en.wikipedia.org/wiki/B%C3%A9zier_curve">http://en.wikipedia.org/wiki/B%C3%A9zier_curve</a> , you can see simple animated examples.</p>
<p>In this example, p0 is 'on the curve', p2 is also 'on the curve', but p1 is 'off the curve'. In other words, p1 is a 'control point'.</p>
<div class="image">
<img src="bezier.gif"  alt="Bezier.gif" title="The Letter B"/>
</div>
<p>The math is not actually as complicated as it looks on the wiki page- you can draw a Bezier Quadratic using only a ruler and a pencil. I.E. you can actually do it without any transcendental functions or complicated algebra, just using simple ratios and integer math. But I digress.</p>
<p>Now... in Truetype there is a special feature in the way off-curve points are listed. If two are listed in a row, then there is actually a 'hidden' or 'implied' on-curve point at a position exactly halfway between them. font_to_svg does not draw these points but they are easy to imagine when looking at the debug code.</p>
<p>Now. How does font_to_svg do SVG output? It basically just copies the point and contour information in the TrueType file and splits it into SVG paths. The actual rendering of the SVG file to something on a computer screen is left to the SVG rendering programs, like web browsers or Inkscape. The most complicated thing that these renderers do is probably the "non-zero winding rule", which is a geometry rule that determines how to properly draw the 'holes' and 'body' contours of a character glyph. font_to_svg doesn't have to worry about that either - it just inserts the svg property 'non-zero' fill-type into the generated SVG and the SVG renderer should take care of the rest.</p>
<p>Please see these sites for more info.</p>
<ul>
<li>Basic Terms: <a href="http://www.freetype.org/freetype2/docs/glyphs/glyphs-3.html">http://www.freetype.org/freetype2/docs/glyphs/glyphs-3.html</a></li>
<li>FType + outlines: <a href="http://www.freetype.org/freetype2/docs/reference/ft2-outline_processing.html">http://www.freetype.org/freetype2/docs/reference/ft2-outline_processing.html</a></li>
<li>FType + contours: <a href="http://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html">http://www.freetype.org/freetype2/docs/glyphs/glyphs-6.html</a></li>
<li>TType contours: <a href="https://developer.apple.com/fonts/TTRefMan/RM01/Chap1.html">https://developer.apple.com/fonts/TTRefMan/RM01/Chap1.html</a></li>
<li>TType contours2: <a href="http://www.truetype-typography.com/ttoutln.htm">http://www.truetype-typography.com/ttoutln.htm</a></li>
<li>Non-zero winding rule: <a href="http://en.wikipedia.org/wiki/Nonzero-rule">http://en.wikipedia.org/wiki/Nonzero-rule</a></li>
<li>SVG paths: <a href="http://www.w3schools.com/svg/svg_path.asp">http://www.w3schools.com/svg/svg_path.asp</a></li>
<li>SVG paths + nonzero: <a href="http://www.w3.org/TR/SVG/painting.html#FillProperties">http://www.w3.org/TR/SVG/painting.html#FillProperties</a></li>
</ul>
<h3>What about rendering multiple characters?</h3>
<p>To do this properly for all languages, you actually need a 'layout engine', like Harfbuzz and/or Pango. These are at present, far beyond the scope of this project.</p>
<p>It may be possible to render strings of characters in 'non-connected' scripts, for example English ( Latin alphabet), or Chinese, using the basic bounding box information. However this library, at present, is probably not very suitable for ligature + combination scripts like Arabic or Devanagari.</p>
<h3>Test characters</h3>
<p>Nice characters that show unusual patterns. Good for testing. </p><pre class="fragment">./example1 FreeSerif.ttf 67 &gt; xa67.svg
./example1 FreeSerif.ttf 68 &gt; xa68.svg
./example1 FreeSerif.ttf 0x2766 &gt; x2766.svg
./example1 FreeSerif.ttf 0x2767 &gt; x2767.svg
./example1 FreeSerif.ttf 0x1f01a &gt; x1f01a.svg
./example1 FreeSerif.ttf 0x48007 &gt; x48007.svg
</pre><h3>Other projects</h3>
<p>Sean Barret's amazing TTF parser + renderer: <a href="https://github.com/nothings/stb/blob/master/stb_truetype.h">https://github.com/nothings/stb/blob/master/stb_truetype.h</a></p>
<p>The "Batik" project does similar stuff. It is Java:</p>
<p><a href="http://xmlgraphics.apache.org/batik/tools/font-converter.html">http://xmlgraphics.apache.org/batik/tools/font-converter.html</a></p>
<h3>Finding A Unicode font</h3>
<p>An easy resource is here:</p>
<p><a href="http://openfontlibrary.org">http://openfontlibrary.org</a></p>
<p>If you have linux, you can explore as follows:</p>
<p>Run 'charmap', under ubuntu, and then right click on interesting looking glyphs. It will give you some rough idea of the font name.</p>
<p>Then do 'locate ttf | grep ttf$' which will give a list of all Truetype font files (w .ttf extensions) on your system .</p>
<p>You can match this up with what you did in Charmap, then maybe you can find the truetype you are looking for.</p>
<h3>Linux non-cmake build</h3>
<pre class="fragment"># BSD/Linux - 

# install freetype using your package manager
# (something like sudo apt-get install libfreetype6-dev)
# then copy a .ttf file to this directory for convenience
cp `locate FreeSerif.ttf | tail -1 ` .
./build.sh
./example1 ./FreeSerif.ttf 66 &gt; /tmp/x.svg 
firefox /tmp/x.svg
</pre><h3>font_to_svg2.hpp</h3>
<p>patched up the font_to_svg.hpp file, it is available as a more up-to-date alternative called font_to_svg2.hpp for your experimentation. It is theoretically faster and easier to use, but contains less debug info.</p>
<h3>Todo</h3>
<p>get real name of glyph (like unicode name)</p>
<p>investigate linux's auto-finding of unicode glyphs</p>
<p>auto-find fonts on linux, not require cmdline fontname?</p>
<p>accept U+4034 (hex) input format</p>
<p>regression test</p>
<p>Long term - opentype? pango / harfbuzz?</p>
<h3>Trademark disclaimer</h3>
<p>TrueType is a trademark of Apple, Inc. This library is not in any way affiliated nor endorsed by Apple, Inc. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Wed Jan 31 2018 21:22:17 for ESP8266 ILI9341 display support code with printf sources, wire-frame viewer and custom fonts by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.11
</small></address>
</body>
</html>
